<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html" />
  <title>MyBatis Generator Feature Debug Reference</title>
  <link type="text/css" rel="stylesheet" href="../mbgdoc/mbgstyle.css"/>
</head>
<body>
<h1>MyBatis Generator Feature Debug Reference</h1>
<p>This page contains reference information about how to build and debug the
MyBatis Generator (MBG) feature from source.</p>

<h2>Feature Structure</h2>
<p>The MBG feature is structured as six different Eclipse projects - a feature project,
four plugin projects, and a project that holds the build scripts.  The feature project
groups the four plugins together for easy installation.  The MBG feature project is
<code>org.mybatis.generator</code>.
That project references the four plugin projects.  The plugin projects are structured as
follows:</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>Plug-in Project</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.core</code></td>
    <td>This plugin holds the Java source for the core MBG library.  The project for
      this plugin contains linked folders to the MBG source tree.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.core</code></td>
    <td>This plugin holds Java support classes for the other plugins.  This plugin does not contribute
        to the Eclipse user interface.  This plugin includes classes for Java file
        merging, and Eclipse implementations of the MBG callback interfaces.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.doc</code></td>
    <td>This plug-in holds the documentation for MBG.  There is a build file in this
      plug-in (buildDoc.xml) that will build the documentation and package it for inclusion
      into the Eclipse help system.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.ui</code></td>
    <td>This plug-in holds the Java code for the Eclipse user interface for MBG.  If you
      are experiencing trouble with the plugin specific features (like the integrated Ant task), then
      the code for those features will be found in this plugin.
    </td>
  </tr>
</table>

<h2>Other Projects</h2>
<p>There are two other Eclipse projects that complete the feature:</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>Project</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>org.mybatis.generator</code></td>
    <td>This project is the Eclipse feature project for MBG.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.build</code></td>
    <td>This project holds the build scripts and properties for the feature build.</td>
  </tr>
</table>

<h2>Eclipse Workspace Setup</h2>
<p>The following instructions show how to setup an Eclipse workspace for building the MBG feature
and plug-ins from the latest source in the Subversion repository.  We assume that you are somewhat
familiar with Subversion and the Eclipse plug-in development environment (PDE).  These instructions
also assume you are using Eclipse version 3.7.1 (Indigo, SR1).</p>
<ol>
  <li>Checkout the latest source code from Subversion
    <ol type="a">
      <li>Create a local directory where the source will be stored (for example
      /MyBatis/generator)</li>
      <li>Check out the source tree from the Subversion repository at
       <a href="https://mybatis.googlecode.com/svn/sub-projects/generator/trunk/">
       https://mybatis.googlecode.com/svn/sub-projects/generator/trunk/</a>
       <b>Note:</b> this will also checkout the source for the MBG core JAR which is required.</li>
    </ol>
  </li>
  <li>Create a new Eclipse workspace directory (for example /EclipseWorkspaces/MBG)</li>
  <li>Start Eclipse and point it to the new workspace directory</li>
  <li><b>Important:</b> make sure that a version 5.0 or higher JDK is configured as the default
     JRE in Eclipse (Window&gt;Preferences&gt;Java&gt;Installed JREs).  A JDK is required - a JRE
     alone will cause problems.</li>
  <li><b>Important:</b> create a path variable named MYBATIS_GENERATOR_SOURCE that points to the
    <code>.../core/mybatis-generator-core/src</code> folder in the source tree from SVN
    (Window&gt;Preferences&gt;General&gt;Workspace&gt;Linked Resources)</li>
  <li><b>Important:</b> the core MBG project requires log4j to compile.  Some eclipse
    distributions do not include log4j.  You can get it by adding the WTP XSL Developer Tools from
    eclipse (Help>Install New Software, etc.)</li>
  <li>Import the plug-in projects into the workspace
    <ol type="a">
      <li>Start the Eclipse project import wizard
        (File&gt;Import&gt;General&gt;Existing Projects into Workspace)
      </li>
      <li>Set the root directory to the "eclipse" sub-directory of the directory where
        you did the SVN checkout (for example, /MyBatis/generator/eclipse)</li>
      <li>Select all six projects, do not copy the projects into
        your workspace.
        The filled out wizard looks like this: <br />
        <p><img src="importWizard.gif" alt="Eclipse Project Import Wizard"/></p>
      </li>
      <li>Press "Finish", wait for the workspace to build.</li>
    </ol>
  </li>
</ol>

<h2>Debugging</h2>
<p>At this point the projects should be successfully compiled in Eclipse.  If you want to
  debug something in the plug-in, you will need to start another instance of Eclipse
  in debug mode.  The following instructions explain how to do this.</p>

<ol>
    <li>Set a breakpoint in the code you would like to debug.</li>
    <li>Double click on the "plugin.xml" file in the "org.mybatis.generator.eclipse.ui"
      project.  This should open the plug-in manifest editor.  If some other editor
      opens, then close the editor, right click on "plugin.xml" and select the
      "Open With&gt;Plug-in Manifest Editor" option.</li>
    <li>Select the "Overview" editor tab</li>
    <li>Take the option to "Launch an Eclipse Application in Debug mode".  This will
    start a new instance of Eclipse in debug mode with the MBG plug-ins installed.</li>
</ol>

<p>Once you have the other instance of Eclipse started you should create a new Java project
 in the new workspace, create and fill out an MBG configuration file, and then run MBG.
 MBG should eventually hit your breakpoint, and then you step through the code.</p>
<p>The following classes will likely be of the most interest in debugging:</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>Class</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.ui.actions.RunGeneratorThread</code></td>
    <td>This class is a thread that runs MBG on the selected configuration file.
      You can set a breakpoint in the <code>run</code> method of this class to follow
      the MBG code generation process from the beginning.
    </td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.core.merge.JavaFileMerger</code></td>
    <td>This class implements the Java file merge function.  You can set a breakpoint
      in the <code>getMergedSource</code> method to follow the merging process.
    </td>
  </tr>
</table>

<h2>Building the Documentation</h2>
<p>The documentation for MBG is integrated into the Eclipse help system.
The documentation is partially generated (Javadocs), partially copied in from the
core MBG source tree, and partially maintained in the plugin itself.
This full documentation set is not in Subversion because it is partially generated.  If you would
like to rebuild the documentation, simply execute the <code>buildDoc.xml</code> file
in the <code>org.mybatis.generator.eclipse.doc</code> project (an Ant build file).</p>

<h2>Building the Feature for Distribution</h2>
<p>If you want to build an updated version of the feature and distribute it locally, then
follow these steps:</p>
<ol>
  <li>Open the file <code>build.xml</code> in the <code>org.mybatis.generator.build</code>
      project.  There are four properties at the beginning of the file that may need to
      change for your local environment.
      <p/>
      <table cellspacing="0" border="1">
        <tr>
          <th>Property</th>
          <th>Description</th>
        </tr>
        <tr>
          <td>baseLocation</td>
          <td>This should be set to the location on disk of an eclipse distribution that
              includes the plug in development environment.
          </td>
        </tr>
        <tr>
          <td>pdeBuildPluginVersion</td>
          <td>This is the version of the <code>org.eclipse.pde.build</code> plugin.
              The value in the file is the correct version for Eclipse 3.7.1
          </td>
        </tr>
        <tr>
          <td>equinoxLauncherPluginVersion</td>
          <td>This is the version of the <code>org.eclipse.equinox.launcher</code> plugin.
              The value in the file is the correct version for Eclipse 3.7.1
          </td>
        </tr>
        <tr>
          <td>buildDirectory</td>
          <td>This is the target directory for the build.</td>
        </tr>
      </table>
      <p/>
  </li>
  <li>Once you have verified or updated the properties, you can close the
      <code>build.xml</code> file.
  <li>Execute the <code>build.xml</code> file (right click, Run As>Ant Build)</li>
</ol>

<p>Once the build executes successfully, the new feature will be available
on your local drive at
<code>/temp/mybatis.generator.build/buildRepo</code>
unless you change the <code>buildDirectory</code> property above.  The easiest way
to install this new version of the feature is to create a new local repository
that points to this directory (Help&gt;Install New Software...) and install
the new version with P2.</p>

</body>
</html>
